.\" Copyright (c) 2010-2018 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd May 2, 2010
.Dt AG_DRIVERMW 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.4.1
.Sh NAME
.Nm AG_DriverMw
.Nd agar multiple-window driver class
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" IMAGE(http://libagar.org/widgets/AG_DriverGLX.png, "The Xorg/glx driver")
.Nm
is a subclass of
.Xr AG_Driver 3
for "multiple-window" drivers (i.e., drivers where Agar must interface with
a native window system).
.Sh INHERITANCE HIERARCHY
.Xr AG_Driver 3 ->
.Nm .
.Sh INTERNAL API
The
.Ft AG_DriverMwClass
structure describes a "multiple-window" graphics driver, where Agar will need
to interface with an existing window manager.
.Ft AG_DriverMwClass
inherits from
.Ft AG_DriverClass
and is defined as follows:
.Bd -literal
typedef struct ag_driver_mw_class {
	struct ag_driver_class _inherit;

	/* Open/close native windows */
	int  (*openWindow)(AG_Window *w, const AG_Rect *r, int bpp,
	                   Uint flags);
	void (*closeWindow)(AG_Window *w);

	/* Show and hide window */
	int (*mapWindow)(AG_Window *w);
	int (*unmapWindow)(AG_Window *w);

	/* Configure stacking order and parenting */
	int (*raiseWindow)(AG_Window *w);
	int (*lowerWindow)(AG_Window *w);
	int (*reparentWindow)(AG_Window *w, AG_Window *winParent,
	                      int x, int y);

	/* Change and query input focus state */
	int (*getInputFocus)(AG_Window **w);
	int (*setInputFocus)(AG_Window *w);

	/* Move and resize windows */
	int  (*moveWindow)(AG_Window *w, int x, int y);
	int  (*resizeWindow)(AG_Window *w, Uint w, Uint h);
	int  (*moveResizeWindow)(AG_Window *w, AG_SizeAlloc *a);
	void (*preResizeCallback)(AG_Window *w);
	void (*postResizeCallback)(AG_Window *w, AG_SizeAlloc *a);

	/* Configure window parameters */
	int  (*setBorderWidth)(AG_Window *w, Uint w);
	int  (*setWindowCaption)(AG_Window *w, const char *s);
	void (*setTransientFor)(AG_Window *w, AG_Window *winParent);
	int  (*setOpacity)(AG_Window *w, float opacity);
	void (*tweakAlignment)(AG_Window *w, AG_SizeAlloc *a);
} AG_DriverMwClass;
.Ed
.Pp
The
.Fn openWindow
operation opens a new "native" window corresponding to an
.Xr AG_Window 3
that is in the process of being created, returning 0 on success or -1 on
failure.
The
.Fa r
argument specifies the preferred location and geometry of the window, in
pixels.
.Fa bpp
specifies a preferred depth in bits per pixels.
The following
.Fa flags
are recognized:
.Pp
.Bl -tag -compact -width "AG_DRIVER_MW_ANYPOS "
.It AG_DRIVER_MW_ANYPOS
Ignore the coordinates in
.Fa r
and let the underlying window system select some default coordinates.
.El
.Pp
.Fn mapWindow
and
.Fn unmapWindow
make a window visible or invisible, returning 0 on success and -1 on failure.
.Pp
.Fn raiseWindow
and
.Fn lowerWindow
respectively raise and lower the window, returning 0 on success and -1 on
failure.
The
.Fn reparentWindow
function arranges for the window to become a child of
.Fa winParent ,
moving it to parent-relative coordinates
.Fa x ,
.Fa y .
The function should return 0 on success or -1 on failure.
.Pp
The
.Fn getInputFocus
operation retrieves a pointer to the window currently holding focus,
returning 0 on success.
If the focus is external to the Agar application, it should return -1.
.Fn setInputFocus
gives focus to the specified window, returning 0 on success or -1 on failure.
.Pp
The
.Fn moveWindow ,
.Fn resizeWindow
and
.Fn moveResizeWindow
operations respectively move, resize or move+resize a window to specified
coordinates and geometry, returning 0 on success or -1 on failure.
.Pp
The
.Fn preResizeCallback
operation is invoked prior to a window resize,
and
.Fn postResizeCallback
is invoked following a window resize (the new window geometry is passed
as the
.Fa a
argument).
.Pp
.Fn setBorderWidth
configures a window border size in pixels, returning 0 on success or -1
if the operation is unsupported or an error has occurred.
.Pp
.Fn setWindowCaption
sets the associated window caption text, if supported by the window system.
The string passed to the function may contain characters in UTF-8 encoding.
The function should return 0 on success or -1 on failure.
.Pp
.Fn setTransientFor
passes a hint to the window manager that the window should be marked as
"transient" for the specified window
.Fa winParent .
This operation is optional and window manager specific.
.Pp
.Fn setOpacity
passes a window opacity argument (ranging from 0.0 to 1.0) to the
underlying window manager.
.Pp
The optional
.Fn tweakAlignment
operation allows the driver to override or alter the effect of the window
alignment request (set by
.Xr AG_WindowSetPosition 3
or
.Xr AG_WindowSetGeometryAligned 3 ) ,
such that underlying WM-specific items (desktop panels and such) can be taken
into consideration (by default, the display boundaries are used).
This routine should set the
.Va x
and
.Va y
members of
.Fa a ,
in function of
.Va w
and
.Va h .
.Sh SEE ALSO
.Xr AG_Driver 3 ,
.Xr AG_DriverSw 3 ,
.Xr AG_InitGraphics 3 ,
.Xr AG_Intro 3
.Sh HISTORY
The
.Nm
class first appeared in Agar 1.4.0.
